Easy Configuration Uitilty
Easy WebServer is a standard interface between a Web Server compliant with ISAPI/NSAPI or CGI and a Activex (or OLE) DLL.

With this software any developer that works with VB, Delphi or C++ or another tool capable of generate Activex DLL's is able to build Web Server Applications, in other words, responding Web requests is easy as write an ActiveX DLL without programming a ISAPI/NSAPI or CGI interfaces.

Easy WebServer have an ISAPI/NSAPI DLL called EasyApi.DLL and a CGI program called EasyGI.Exe, both are  thin layers that invoke custom ActiveX DLL's, passing arguments to them from the Web Request and receiving the response sending it back to the Web Server.

The following figure show how Easy WebServer works:


Easy Configuration Utility


Configuring MetaVariables

MetaVariables can be defined in General Tab of Configuration Utility main screen.

They are displayed in a Tree View where Parent Items are MetaVariables Names and children Items are MetaVariables values.

To add a MetaVariable press "New..." button from the toolbar or choose File New... option from main menu, this will automatically add a new item in TreeView, then you should edit Name and Value for this new metavariable.

At any moment you can edit either Name or Value of a MetaVariable, with a doble click on it.


Out (Response) Arguments
Actions definition is configured in "Actions Tab" of the main screen of Easy Configuration Utility.

To Add an action you can press "New..." button from the toolbar or choose File New... option from main menu, then Easy Configuration Utility will prompt you for a name for New Action when you press OK Button it will add a new element in "Actions Tree", as you see in figure below:

Under NewAction item (Where NewAction is the actual Name of the Action), there are the following SubItems:

I Under this subitem you can edit PathInfoTopic10 for this action.

OLEServer: Under this subitem you can edit OLE Class StringTopic10 which will be invoked in order to process a request for this action

Method: Under this subitem you can edit the MethodTopic10 or function name which will be called after OLEServer be invoked.

Request and Response Arguments: Under this subitems you will add all arguments which are received by Method or function defined above. To add a new argument select Request Arguments or Response Arguments then press "New..." button from the toolbar or choose File New... option from main menu, the following window dialog will appear:

In Type Argument select from the list which Request or Response argument will be received and in "Name in OLE Server" box type the actual name of this argument as is defined in your OLE Server. Then press OK button and under the selected item in the three will be added an item with tell you about the Type Argument, and under this one is the Name in your OLE Server.

Remember define all the arguments with its corresponding data type, also, define Request arguments by value (ByVal in Visual Basic) and Response arguments by reference (ByRef in Visual Basic).

In this screen you should define Default Action to do this, simply check the Default Action Box when the Name of the action is selected.


General Parameters
Easy WebServer (EasyApi.DLL and EasyGI.EXE) needs some General Parameters that tell them how they  must work. These can be changed in Configuration Utility.

General Parameters are:

Maximum Number of Concurrent Connections: Easy WebServer creates a new thread when it receives a new request and all threads already created are busy, in other words, it have a thread for each concurrent connection, with this parameter you can  limit the number of threads created in order to save Windows resources according with your server capacity.

NOTE: In trial versions this value is always 1, no matter if you change it in Configuration Utility.

Load Params On: Indicates to Easy Web Server when must load these General Parameter. There are three possible values:

Load EasyAPI.DLL/EasyGI.EXE. This mean Easy WebServer will read General Parameter 	as soon as it is invoked by the Web Server.

New thread, Easy Web Server will read General Parameters when it creates a new thread 	for handling a new concurrent connection.

Before Dispatch, Easy Web Server will read parameters when it receives a new request.

NOTE: For EasyGI.EXE  two first options are equivalent because the Web Server Loads and Unloads a CGI program  for each request.

The first option is the most efficient, however, the other ones are useful when you are testing or debugging your OLE servers.

Cache Connections: Each time an ISAPI server receives a request message, it creates a thread to handle it .In order to improve performance, these threads can be saved in a cache when the thread associated with the HTTP request message finishes executing. For EasyGI.Exe this parameter has not any relevance.


Meta Variables
Meta Variables are an easy way to mantain or modify your HTML responses without modify code.

They are keywords enclosed between a prefix and a postfix (in order to identify them) that are replaced at run time by their corresponding value as  you defined in Easy configuration utility

By example if you want to display the same background image in all your HTML pages, you can use a Meta Variable called Backgrd, then define its value, it could be images/Back.jpg;

Supose that you have defined Meta Variable Prefix = ## and Meta Variable Post Fix = ##, so you can return inside your HTML response the following line:

<BODY BGCOLOR="#FFFFFF" BACKGROUND="##BACKGRD##">

Instead of:

<BODY BGCOLOR="#FFFFFF" BACKGROUND="images/Back.jpg">

Easy Web Server will replace the string ##BACKGRD## by images/Back.jpg before it sends the response back.

The main advantege of Meta Variables is the easy way to make changes to your HTML pages. In the above example if you wish change your background image for all pages, you would make this change in Easy Configuration Utility, instead of do that in each page, saving mantainance time and cost.

Note Meta Variables are not case sensitive, and Prefix and Postfix is not required, they are just an easy way to identify metavariables and avoid undesired results by coincidences.


Actions
Action is the way how Easy Web Server manages a request from the client.

In the following example: http://www.Server.Com/Scripts /EasyApi.dll/Animals?Id=DOG. The action could be Animals.In other words the "path" between  EasyApi.Dll/  and ? (question mark) defines which  action of the Web Server should be invoked. So, only one CGI or ISAPI Web Server is able to manage different requests.

An action in Easy Web Server is formed by:

PathInfo: In the above example /Animals is the PathInfo.

OLE Server: It`s an class string of  an OLE object that is loaded by Easy Web Server when it receives the action assocated with.

Method: It´s the function or method of the OLE Server that is invoked and it is responsible to assemble the web response.

Request Response Arguments: These are the actual and formal arguments or parameters defined in the method interface. Request arguments contain information about the client request and it will be passed by value and Response Arguments will be filled by the Method  in order to prepare the response, therefore they will by passed by Reference.

In Configuration Utility you can define actions and their associated information so that Easy Web Server could invoke the right function by OLE Automation and send it back to the client as is described in Introduction.Therefore Actions are the heart of Easy Web Server so  it must be well defined in Configuration Utility.

You can define a Default Action, that is an action which is loaded when Pathinfo does not match with any defined in Configuration Utility.


Out (Response) Arguments


Planning your work


Receiving and returning arguments


Returning responses


Easy Server Components

Easy Web Server Registration

Registration fee: $67

If you would like to register Easy Web Server, you can do the registration online on the

Internet at http://www.shareit.com/programs/102456.htm. Alternatively, you can go to

http://www.shareit.com and enter the program number there: 102456. If you do not have access

to the Internet, you can register via phone, fax or postal mail. Please print out the

following form, and fax or mail it to:

ShareIt!

element 5 AG

Habsburgerring 3

50674 Koeln

Germany

Phone: 	        +49-221-2407279

Fax: 	+49-221-2407278

E-Mail:         register@shareit.com

US customers may also order by calling 1-800-903-4152 (orders only please!). US check and

cash orders can be sent to our US office at

ShareIt! Inc.

PO Box 844

Greensburg, PA 15601-0844

USA

Tel. 724-850-8186

Fax. 724-850-8187

Registration form for Easy Web Server

Program No.: 102456

Last name: ___________________________________

First name: ____________________________________

Company: ____________________________________

Street and #: ______________________________________

City, State, postal code: ________________________________

Country: _______________________________________

Phone: _____________________________________

Fax: ________________________________________

E-Mail: ______________________________________

How would like to receive the registration key/full version?

e-mail 	- fax	- postal mail

How would you like to pay the registration fee of $67:

credit card - wire transfer - EuroCheque - cash

Credit card information (if applicable)

Credit card: Visa - Eurocard/Mastercard - American Express - Diners Club

Card holder: ________________________________

Card No.: ___________________________________

Date of Expiration : ___________________________________

Date / Signature ___________________________


EasyApi.DLL and EasyGI.EXE
EasyApi.DLL is an ISAPI Web Server Application and EasyGI.EXE is a CGI Web Server Application. They work similarly and you can use them exactly in the same way, this means you can program OLE Servers that handles web requests with Easy Web Server rules and you can use either EasyApi or EasyGI without any modification of your code or Configuration.

Decision about which one you should use it will make on advantages and disadvantages of both technology standards on your web site features.

They are thin layers that encapsulates all hard work of a Web server application (receive HTTP request messages from the Web server,  performs any actions requested in those messages,  formulate responses that it passes back to the Web server). So you can concentrate only in prepare and build responses for the client request, through OLE Servers.


Action
This parameter informs your Ole Server what is the kind of request that it is receiving.

Your OLE Server should read the request message and assemble a response. In Configuration Application you define what actions you are going to handle and which is your default action. For Example in the following request: http://www.Server.Com/Scripts /EasyApi.dll/Animals?Id=DOG. The action could be Animals.

Type: String.


Accept Auth
It contains authentication information  about the client that sent the request message.

 Authorization allows your OLE Server to provided limited access to the resource specified by the URL property. For more information about HTTP authentication schemes, see the Internet standards documentation.

Type String.


Cache-Control
Read CacheControl to determine any web client directives that must be obeyed by all caching mechanisms along the request/response chain. The CacheControl directives of the HTTP request do not need to apply to the corresponding HTTP response.

The HTTP 1.1 standard defines the following directives for CacheControl:

no-cache	The request may not be cached. The web server validates the request before the TISAPIRequest object is created.

no-store	The request contains sensitive information and may not be stored on any permanent medium such as a back-up tape. If the request is stored temporarily in a file, the file must be deleted.

max-age=ss	The request is considered invalid if it is older than ss seconds. This directive takes precedence over the Expires property, even if Expires is more restrictive. Invalid requests are validated by the web server before the TISAPIRequest object is created.

max-stale or max-stale=ss	The client is willing to accept a response that has exceeded its expiration time. The max-stale directive can optionally specify the number of seconds by which the response can exceed its expiration time.

min-fresh=ss	The client is not willing to accept a response that expires in less than ss seconds.

Type String.


Connection
This parameter has the options requested by the web client for its connection to the server application.

The HTTP 1.1 standard specifies only one value for the Connection header. If the value of Connection is close, then the connection should be closed after the completion of the response.

Type String.


Request Content
RequestContent: This contains request message that is sending information to the server. The value of Content depends on the Method of the HTTP request. When the Method is POST, Content is the unparsed string giving the values to be posted with their associated fields. When the Method is PUT, Content is the value that should replace the URL.

Type String.

 RequestContentEncoding This is a comma separated list of the mechanisms that have been applied (if any) to the Content of the HTTP request. The encoding mechanisms are listed in the order in which they were applied by the web client.

Type String.

 RequestContentType ContentType  determines the media type of the Content of the HTTP request message. The ContentType is a string of the form Type/SubType.

Type String.

 RequestContentVersion ContentVersion  determines the version of the Content of the HTTP request message. Most HTTP requests do not require any Content at all. When the Method requires a value for Content, the ContentVersion may be set to indicate the version of the source of that content. The format of the ContentVersion depends on the ContentType of the request.

Type String.


RequestContentEncoding


RequestContentType


InCookie
This parameter is  "cookie" string sent from the web client request.

Cookie is the unparsed value of the Cookie header. The Cookie header can include multiple fields separated by semicolons (;)

Type String.


ReqDate
This contains the date and time at which the HTTP request message originated.

Date can be used to determine whether the Content of the request is still valid.

Type Date Time.


Derived-From
Is  the URL where the value of Content originated

Type String.


RequestExpires
This parameter is the date and time at which the request becomes invalid.

Type Date Time.


From
From contains information about  the Internet e-mail address of the user for whom the web client sent the HTTP request message.

It can be useful and a protected environment.

Type String


LocalHost
It determines the Internet host and port number of resource being requested.

For Example in the following request:

http://www.Server.Com/Scripts /EasyApi.dll/Animals?Id=DOG. The LocalHost Parameter is www.Server.Com.

 Type String.


RequestLastModified
This parameter is useful is with a Method= GET to determine whether the request is conditional.

If the information requested by the web client was not modified since the time indicated by IfModifiedSince, the response should be a not modified error rather than the information indicated by the URL property.

The value of IfModifiedSince is given according to the local clock of the  Web Server  not the clock of the web client.

Type Date time.


Path
This is the value of the path information (if any) of the URL specified in the HTTP request message.

For Example: http://www.Server.Com/Scripts/EasyApi.dll/Animals?Id=DOG. Path = Animals. In Configuration Utility you can associate a Path to an action

Type String.


PathTranslated
This is a translation of the Path parameter to a  path on the Web server.

Type String.


ProtocolVersion
This parameter indicates version number of the HTTP protocol specified in the initial header of the HTTP request message.

Type String.


Query
This parameter may include multiple pair fields separated by ampersands (&).

It includes query information (if any) of the URL specified in the HTTP request message. For Example: http://www.Server.Com/Scripts /EasyApi.dll/Animals?Id=DOG. Query  is Id=DOG.

Type String


Referer
Referer is the value of the Referer header of the HTTP request message. It determines the URL of the resource where the HTTP request message originated.

Type String


RemoteAddress
This parameter contains a string with the TCP/IP address of the web client that originated the request.

Type String.


RemoteHost
This parameter contains a string with the fully qualified reverse domain lookup of the web client that originated the request.

Type String.


ScriptName
This is the value of the script information  of the URL specified in the HTTP request message.

For Example: http://www.Server.Com/Scripts/EasyApi.dll/Animals?Id=DOG. ScriptName is /Scripts/EasyApi.

Type String.


Port
It is the port number of the port on the web server that receives the HTTP request message.

Type String.


Title
It  is the value of the Title header of the HTTP request message.

Type String


Descriptors
It is the value of the User-Agent header of the HTTP request message.

It contains one or more descriptors, in order of significance. Each descriptor gives the name of the product or application that generated the request, or a comment about the client that orignated the request.

Type String


Method
Method is the value of the Method header of the HTTP request message.

The HTTP 1.1 standard defines the following methods

OPTIONS A request for information about available communication options.

GET	A request for the information identified by the URL property.

HEAD	A request for information about the properties of the HTTP response, but not for the content of the response.

POST	A request for the server application to post the data included in the Content property, as appropriate.

PUT	A request for the server application to replace the resource indicated by the URL property with the data included in the Content property.

DELETE A request for the server application to delete or hide the resource identified by the URL property.

TRACE	A request for the server application to send a loop-back to confirm receipt of the request.

Type String.


Allow
Fill Allow parameter to indicate what type of request methods the server application can respond to for the URL specified in the HTTPRequest.

Allow is a string of method names, separated by commas. The method names can include any pre-defined methods from the HTTP standard, or any additional methods implemented by the server application

Type: String.


ResponseContent
ResponseContent The meaning of this parameter depends of your kind of response:

HTMLFile Content is the File Name which will bet sent back to the client.

HTML String Content is the information sent to the web client in response to an HTTP request message, and it can be a string of HTML commands, the name of an HTML file, graphic content such as a bit-stream, or any other MIME content type.

URL: Content is then URL string that you are redirecting your response.

Type: String

ResponseContentEncoding. This should be a comma separated list of the mechanisms that have been applied (if any) to the Content of the HTTP response. The encoding mechanisms are listed in the order in which they were applied by the web client. It only applies for responses of Kind HTML String

Type String.

ResponseContentType ContentType  determines the media type of the Content of the HTTP response message. The ContentType should be a string of the form Type/SubType. It only applies for responses of Kind HTML String

Type String.

Response ContentVersion ContentVersion  determines the version of the Content of the HTTP response message. Most HTTP requests do not require any Content at all. When the Method requires a value for Content, the ContentVersion should be set to indicate the version of the source of that content. The format of the ContentVersion depends on the ContentType of the response. It only applies for responses of Kind HTML String

Type String.


FromURL
It is the URI of the resource where the Content of the HTTP response originated.

 Set DerivedFrom to the URI where the value of Content originates. It is especially important to set DerivedFrom when the Content of the HTTP response did not originate from the resource indicated by the URL property of the HTTP request message.

Type: String.


ResponseExpires
Expires specifies the date and time after which the Content of the HTTP response message should be considered invalid.

Type DateTime.


ResponseLastModified
LastModified indicates the date and time that the value of the Content property was last updated. This is useful for web clients to know if its local version is up to date or they need to download it again.

Type: Date Time


CompleteIn
This should be used to indicate the URL of a resource the web client should point to for the completion of its request.

Type: String


LogString
It  is a descriptive string included in the HTTP response message for event logging purposes.

Type: String


AccessProtected
This parameter is used when the HTTP response message returns 401 (Unauthorized) or 402 (Payment required).

It is the name of a set of URLs that require a password or payment before the web client can access them

Type:String


ReasonString
It  is an informative text string that indicates the status of the response to the web client request.

You should use this parameter to   inform the web client of the success or failure of the HTTP request message

Type:String.


ServerCode
This  is a 3-digit integer that indicates the status of the response to the HTTP request message.

You can set  ServerCode to inform the web client the status of the HTTP request message. Server codes are standard return values that can be interpreted by all web clients. Each status code has a corresponding reason string that provides a human web client with a more understandable indication of the status.

Type:Integer.


Title
Title specifies a title for the Content of the HTTP response message.

Type:String


Version
Version is the HTTP protocol version number that the web client is using. The value of this parameter is taken from ProtocolVersion Request parameter.

Type: String.


Authenticate
It consists of an authentication scheme name, followed by a comma-separated list of parameter/value pairs that specify the parameters to the authentication scheme.

Type: String


ReplaceMetaVars
It indicates if you want EasyApi.Dll or EasyGI.Exe replace meta Variables with their actual values if your kind of response is HTMLFile or HTMLString.

If this parameter is set to Zero replacement not will achieve otherwise replacement will achieve. Default values is 1.

Type:String.


Cookies
CookieNames: Specifies the names of the custom fields represented by  Cookie headers.

CookieValues: Specifies thes values of the Cookie headers field named by the CookieNames argument.

CookieDomains: Specifies the Domain fields of the cookie headers.

CookieExpires: Specifies when the cookies are no longer valid.

CookiePaths: Identifies the paths of URLs to which the Cookies should be sent.

CookieSecuresHeaders:Determines whether the Web client must use a secure connection to pass on the Cookie headers.

These arguments are used to send back cookies to the client, they are strings arguments which are used to build a cookie header in the response. Each argument corresponds a field in a cookie header and must contain all the values in the cookie set that you are returning, these values should be separated by a CRLF (Ascii 13 and Ascii 10). By example if you are returning two cookie headers CookieNames should be like this:

     CookieNames = "Cookie1" & Chr(13) & Chr(10) & "Cookie2".

And the rest of cookie Arguments must be filled in the same way.


Response Kinds
Using Easy Web Server you must create a set of Activex DLL's, which will receive information about the client request through arguments passed by value, and will send back the response content through arguments passed by reference.

Request arguments are called In Arguments and Response arguments are called Out Arguments.

Meaning of Out arguments depends on the Response kind. The response Kind is the returning value of your Activex DLL Method that Easy Web Server is invoking. This means thay all methods of your Activex DLL's must be a function an must return one of the following integer values:

RspURL (0): Easy Web Server redirects the response to address indicated in Response content argument. There are no metavariables substitution.

RspFileName (1): Easy Web Server receives a File Name in Response Content Argument. This file must be a HTML Page and will be opened by Easy Web Server, Metavariables will be replaced, if any, and then the response will send back. Easy Web Server won't modify the HTML Page, it will be only read.

RspHTMLString(2): Easy Web Server receives directly  HTML code in Response Content Argument, Metavariables will be replaced, if any and then the response will send back.

RspOther (3): Easy Web Server receives a set of Out Arguments like Cookies, Server Code, Reason String, etc. With these, a HTML response will be built. This option is useful if you are not familiarized with HTML standard, however, you must set all the Out Arguments required in order to have a complete response and there are no metavariables substitution.


Configuring General Parameters

General Parameters can be set in General Tab of Main Screen of Easy Configuration Utility.

"Maximum Number of Concurrent connections" is an integer between 1 and 32768.

In "Load params On" you have to select one of the three available options according with explanation in Basic Concepts Section.

"Cache Connections" is a check box that indicate if you want Easy Web Server keep a list of threads used in the current session according with explanation in Basic Concepts Section.

After set this parameters you can save them by pressing Save Button from Toolbar of selecting File Save from menu. If choose Exit or "Actions" tab without saving any change, Configuration Utility will prompt if you want to save changes.

Under General Parameters there is MetaVariables Configuration


Actions definition is configured in "Actions Tab" of the main screen of Easy Configuration Utility.

To Add an action you can press "New..." button from the toolbar or choose File New... option from main menu, then Easy Configuration Utility will prompt you for a name for New Action when you press OK Button it will add a new element in "Actions Tree", as you see in figure below:

Under NewAction item (Where NewAction is the actual Name of the Action), there are the following SubItems:

PathInfo: Under this subitem you can edit PathInfoTopic10 for this action.

OLEServer: Under this subitem you can edit OLE Class StringTopic10 which will be invoked in order to process a request for this action

Method: Under this subitem you can edit the MethodTopic10 or function name which will be called after OLEServer be invoked.

Request and Response Arguments: Under this subitems you will add all arguments which are received by Method or function defined above. To add a new argument select Request Arguments or Response Arguments then press "New..." button from the toolbar or choose File New... option from main menu, the following window dialog will appear:

In Type Argument select from the list which Request or Response argument will be received and in "Name in OLE Server" box type the actual name of this argument as is defined in your OLE Server. Then press OK button and under the selected item in the three will be added an item with tell you about the Type Argument, and under this one is the Name in your OLE Server.

Remember define all the arguments with its corresponding data type, also, define Request arguments by value (ByVal in Visual Basic) and Response arguments by reference (ByRef in Visual Basic)


What is an Out (Response) Argument?
In (Request) arguments are all the information available about the Client Request, so Easy Web Server sends to your OLE Server, as a Function arguments.


What is an Out (Response) Argument?
Out (Response) arguments are all the information which will be used to send back  Response to the Client, so Easy Web Server sends to your OLE Server, as a Function arguments passed by reference in order to be assigned in OLE Server.


Programming your Activex DLL's
Before you develop your Activex DLL (OLE Server), you must define which services you will provide, then you can follow these steps:

Define Actions that will handle all these services.

For each action define Name, Path Info and a brief explanation about how it will work and what kind of responses will send back.

Define how many ActiveX DLL you will need, and for each ActiveX DLL how many public functions or methods will be included. The most common way to do that is develop only one ActiveX DLL and inside it include one method for each Action, however it could change depending on different factors like workload, if some actions are similar and they could  be processed in the same method, etc.

Decide if MetaVariables would be useful. Make a list of metavariables (if any) and their values.

For each function or method you should define whick In (Request) arguments will be received and which Out (Response) Arguments will be send back.

Also, for each function or method you should define what response kind will be used, according with the advantages and disadvantages of each available kind.

Tell Easy Web Server your requirements through Easy Configuration Utility.

Develop your ActiveX DLL(s) according to your definitions.

Enjoy your Web Site!